home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / TEGL6B.ARJ / TUTOR.COM / MENUS.TXT < prev    next >
Text File  |  1991-08-16  |  11KB  |  358 lines
  1. MENUS
  2. -------------------------------------------------------------------
  3.  
  4. The TEGL WINDOWS TOOLKIT II provides an extensive number of menu
  5. functions. You can create bar menus and pull-down (or up) menus.
  6. The basic item in a TEGL menu is the Option Menu. These are accessed
  7. through a pointer, an OptionMPtr.
  8.  
  9. Creating a bar menu require a few steps. First we have to create
  10. some option menus to attach to the bar menu. To do this use the function
  11. CreateOptionMenu. It is declared as follows:
  12.  
  13. Function CreateOptionMenu(FontType: Pointer): OptionMPtr;
  14.  
  15. FontType is the font to use when displaying the menu selections. The
  16. OptionMPtr that is returned is used to add selections to the option
  17. menu and is finally attached to a bar menu (or mouse click area).
  18.  
  19. After the option menu has been created us DefineOptions to add selections
  20. to the menu.
  21.  
  22. Procedure DefineOptions(VAR om; OptionMPtr; EntryStr : String;
  23.                  Active : Boolean; Event: CallProc);
  24.  
  25. The first parameter, om, is the optionmptr that must have been created
  26. with DefineOptions. EntryStr is the text that will be displayed for the
  27. menu selection. Active sets whether the menu item can be selected, if
  28. TRUE then it can be selected, when FALSE it cannot and will appear in
  29. a lighter shade than the other menu selections. Event is the event-handler
  30. that will be called when the menu selection is clicked on.
  31.  
  32. The '-' (hypen) is used to place a separator line between options, it will
  33. appear as continuous line. When adding a separator the Active parameter
  34. should alway be FALSE and the Event should be NilUnitProc which is a
  35. place holder event-handler that just returns.
  36.  
  37. Note that menu selections (either bar or option menu) can have the tilde
  38. character '~' placed around one of the characters in the text for the menu
  39. selection. When this item is displayed the character will be underscored
  40. and the corresponding key will be trapped for.
  41.  
  42. The next step is create a bar menu that the option menu('s) can be attached
  43. to. To do this we use CreateBarMenu.
  44.  
  45. Procedure CreateBarMenu(x, y, length : Word);
  46.  
  47. x, y is the postion (in absolute screen coordinates) where the bar menu is
  48. to be placed. Length is the length of the menu in pixels.
  49.  
  50. The font that is used to display the bar menu is the current font, if you
  51. want to use a specific font use SetTeglFont before calling CreateBarMenu.
  52.  
  53. Hint: A bar menu is really just a long narrow frame, and like any frame
  54. you change certain characteristics. Sometimes it might be useful to save
  55. the StackPtr right after creating a bar menu.
  56.  
  57. When the bar menu has been created the option menus are attaced to it using
  58. OutBarOption.
  59.  
  60. Procedure OutBarOption(EntryStr: String; om: OptionMPtr);
  61.  
  62. The EntryStr is the bar menu selection and om is the option menu that will
  63. appear when the selection is made. The option menu will appear as a drop
  64. down or drop up menu depending on where the bar menu is located.
  65.  
  66. Here is a small but complete program example of a bar menu with just
  67. one selection. The one selection is an option menu with the entries:
  68. 'File' which does nothing, '-' which gives a separator line (for
  69. appearance sake, and 'Exit' which will end the program.
  70.  
  71. Note: NilUnitProc is an event-handler which does nothing. It can be used
  72. as place holder when you are creating the menu interface of program but
  73. haven't completed the guts, and it is also used where an event parameter
  74. (even one that is never called) is required.
  75.  
  76. BEGINFILE> menu1.pas
  77. {-- menu1.pas }
  78. {$F+}
  79. USES
  80.   fastgrph, teglfont, tgraph, teglunit, teglmain, teglmenu;
  81.  
  82.  
  83. function ExitOption(ifs : ImageStkPtr; Ms: MsClickPtr): Word;
  84.   BEGIN
  85.     Halt;
  86.   END;
  87.  
  88. VAR  OmFile : OptionMPtr;
  89.  
  90. BEGIN
  91.   easytegl;
  92.   easyout;
  93.  
  94.   OmFile := CreateOptionMenu(@f8x12bol);
  95.   DefineOptions(OmFile,' ~O~pen ',true,NilUnitProc);
  96.   DefineOptions(OmFile,'-',false,nilunitproc);
  97.   DefineOptions(OmFile,' E~x~it ',true,ExitOption);
  98.   SetTeglFont(@f8x12bol);
  99.   CreateBarMenu(0,0,getmaxx);
  100.   OutBarOption(' ~F~ile ',OmFile);
  101.  
  102.   TeglSupervisor;
  103. END.
  104. ENDFILE>
  105.  
  106. We can nest menus arbitrarily deep. To do this we use
  107.  
  108. DefineOptionsSub(OM: OptionMPtr; EntryStr: String; Active: Boolean;
  109.                  OM2: OptionMPtr);
  110.  
  111. This simply attaches an option menu selection that is another option
  112. menu as opposed to an event-handler. As you can see the last parameter
  113. is an OptionMPtr.
  114.  
  115. This example adds two levels of menus, they don't do anything (that's
  116. up to you) but it illustrates the use.
  117.  
  118. BEGINFILE> menu2.pas
  119. {-- menu2.pas }
  120. {$F+}
  121. USES
  122.   fastgrph, teglfont, tgraph, teglunit, teglmain, teglmenu;
  123.  
  124.  
  125. function ExitOption(ifs : ImageStkPtr; Ms: MsClickPtr): Word;
  126.   BEGIN
  127.     Halt;
  128.   END;
  129.  
  130. VAR
  131.      menufont : pointer; {-- by setting the font into a pointer we can }
  132.                          {-- more easily change our selection of the font}
  133.                          {-- to use. }
  134.      OmFile : OptionMPtr;
  135.      OMFile2 : OptionMPtr;
  136.      OmFile3 : OptionMPtr;
  137.  
  138. BEGIN
  139.   easytegl;
  140.   easyout;
  141.  
  142.   menufont := @f8x12bol;
  143.  
  144.   OmFile3 := CreateOptionMenu(menufont);
  145.     DefineOptions(OmFile3,' ~T~o floppy ',true,NilUnitProc);
  146.     DefineOptions(OmFile3,' ~F~rom floppy ',true,NilUnitProc);
  147.  
  148.   OmFile2 := CreateOptionMenu(menufont);
  149.     DefineOptions(OmFile2,' ~F~ormat ',FALSE,NilUnitProc);
  150.     DefineOptions(OmFile2,' ~D~elete ',FALSE,NilUnitProc);
  151.     DefineOptionsSub(OmFile2,' ~C~opy ',true,OmFile3);
  152.  
  153.   OmFile := CreateOptionMenu(menufont);
  154.   DefineOptions(OmFile,' ~O~pen ',true,NilUnitProc);
  155.   DefineOptionsSub(OmFile,' ~D~os functions ',true,OmFile2);
  156.   DefineOptions(OmFile,'-',false,nilunitproc);
  157.   DefineOptions(OmFile,' E~x~it ',true,ExitOption);
  158.  
  159.   SetTeglFont(menufont);
  160.   CreateBarMenu(0,0,getmaxx);
  161.   OutBarOption(' ~F~ile ',OmFile);
  162.  
  163.   TeglSupervisor;
  164. END.
  165. ENDFILE>
  166.  
  167.  
  168. Some people really get carried away when it comes to making menus,
  169. generally we don't recommend really long menus and try to keep them
  170. under several hundred items.
  171.  
  172. This example just shows what happens when an excessive number of menu
  173. selections is added to an option menu.
  174.  
  175. BEGINFILE> menu3.pas
  176. {-- menu3.pas }
  177. {$F+}
  178. USES
  179.   fastgrph, teglfont, tgraph, teglunit, teglmain, teglmenu;
  180.  
  181.  
  182. function itos(i: Integer): String;
  183.   var s :string;
  184.   BEGIN
  185.     str(i,s);
  186.     itos := s + ' ';
  187.   END;
  188.  
  189. function ExitOption(ifs : ImageStkPtr; Ms: MsClickPtr): Word;
  190.   BEGIN
  191.     Halt;
  192.   END;
  193.  
  194. VAR  OmFile : OptionMPtr;
  195.      OmOpen : OptionMPtr;
  196.      i      : Integer;
  197. BEGIN
  198.   easytegl;
  199.   easyout;
  200.  
  201.   OmOpen := CreateOptionMenu(@f8x8Bold);
  202.     for i := 1 to 50 do
  203.       DefineOptions(OmOpen,' file '+itos(i),random(2)=1,NilUnitProc);
  204.  
  205.   OmFile := CreateOptionMenu(@f8x12bol);
  206.   DefineOptionsSub(OmFile,' ~O~pen ',true,OmOpen);
  207.   DefineOptions(OmFile,'-',false,nilunitproc);
  208.   DefineOptions(OmFile,' E~x~it ',true,ExitOption);
  209.   SetTeglFont(@f8x12bol);
  210.   CreateBarMenu(0,0,getmaxx);
  211.   OutBarOption(' ~F~ile ',OmFile);
  212.  
  213.   TeglSupervisor;
  214. END.
  215. ENDFILE>
  216.  
  217. A useful item to have in a menu is a check-marked item. These are usually
  218. boolean flags to indicate some sort of preference. There is a special
  219. option menu item for this:
  220.  
  221. DefineOptionsCheck(OM: OptionMPtr; EntryStr: String; Active: Boolean;
  222.         Event: CallProc; VAR ChkMark : Boolean);
  223.  
  224. The big distinction here is that we pass a variable to the routine so
  225. that when it is selected the variable will be toggled. After the variable
  226. is updated then the event-handler is called, presumably to do some
  227. processing if required. Our example doesn't do this, but you probably
  228. get the idea.
  229.  
  230. When the item is TRUE then a check mark is displayed next to it, when
  231. FALSE no check mark.
  232.  
  233.  
  234. BEGINFILE> menu4.pas
  235. {-- menu4.pas }
  236. {$F+}
  237. USES
  238.   fastgrph, teglfont, tgraph, teglunit, teglmain, teglmenu;
  239.  
  240.  
  241. function ExitOption(ifs : ImageStkPtr; Ms: MsClickPtr): Word;
  242.   BEGIN
  243.     Halt;
  244.   END;
  245.  
  246. VAR
  247.      menufont : pointer;
  248.      OmFile : OptionMPtr;
  249.  
  250. CONST
  251.     FullPath : Boolean = True;
  252.  
  253. BEGIN
  254.   easytegl;
  255.   easyout;
  256.  
  257.   menufont := @f8x12bol;
  258.  
  259.  
  260.  
  261.   OmFile := CreateOptionMenu(menufont);
  262.   DefineOptions(OmFile,' ~O~pen ',true,NilUnitProc);
  263.   DefineOptionsCheck(OmFile,' ~F~ull path ',true,nilunitproc,fullpath);
  264.   DefineOptions(OmFile,'-',false,nilunitproc);
  265.   DefineOptions(OmFile,' E~x~it ',true,ExitOption);
  266.  
  267.   SetTeglFont(menufont);
  268.   CreateBarMenu(0,0,getmaxx);
  269.   OutBarOption(' ~F~ile ',OmFile);
  270.  
  271.   TeglSupervisor;
  272. END.
  273. ENDFILE>
  274.  
  275. Another useful kind of check mark is one where there can be a limited
  276. number of choices but more than just a boolean toggle.
  277.  
  278. DefineOptionsRadio(OM : OptionMPtr; EntryStr: String; Active: Boolean;
  279.               Event: CallProc; EntryRadioValue: Word; VAR ChkVar: Word);
  280.  
  281.  
  282. Here the distinction is ChkVar is a Word value, so you could have
  283. a lot of choices but generally this kind of item is used for 2 to 5 or
  284. perhaps a few more. Each item that uses the same ChkVar must have
  285. a different EntryRadioValue. As with DefineOptionsCheck the event-handler
  286. is called after the variable has been updated.
  287.  
  288. BEGINFILE> menu5.pas
  289. {-- menu5.pas }
  290. {$F+}
  291. USES
  292.   fastgrph, teglfont, tgraph, teglunit, teglmain, teglmenu;
  293.  
  294.  
  295. function ExitOption(ifs : ImageStkPtr; Ms: MsClickPtr): Word;
  296.   BEGIN
  297.     Halt;
  298.   END;
  299.  
  300. VAR
  301.      menufont : pointer;
  302.      OmFile : OptionMPtr;
  303. CONST
  304.      SortOption : Word = 1;
  305.  
  306. BEGIN
  307.   easytegl;
  308.   easyout;
  309.  
  310.   menufont := @f8x12bol;
  311.  
  312.  
  313.   OmFile := CreateOptionMenu(menufont);
  314.   DefineOptions(OmFile,' ~O~pen ',true,NilUnitProc);
  315.   DefineOptions(OmFile,'-',false,nilunitproc);
  316.   DefineOptionsRadio(OmFile,' ~N~ame ',true,nilunitproc,1,SortOption);
  317.   DefineOptionsRadio(OmFile,' ~E~xtension ',true,nilunitproc,2,SortOption);
  318.   DefineOptionsRadio(OmFile,' ~D~ate ',true,nilunitproc,3,SortOption);
  319.   DefineOptionsRadio(OmFile,' N~o~ne ',true,nilunitproc,4,SortOption);
  320.   DefineOptions(OmFile,'-',false,nilunitproc);
  321.   DefineOptions(OmFile,' E~x~it ',true,ExitOption);
  322.  
  323.   SetTeglFont(menufont);
  324.   CreateBarMenu(0,0,getmaxx);
  325.   OutBarOption(' ~F~ile ',OmFile);
  326.  
  327.   TeglSupervisor;
  328. END.
  329. ENDFILE>
  330.  
  331.  
  332. PREFERENCES
  333.  
  334. You can set a number of items to suit your needs or preferences
  335. for menus.
  336.  
  337. SetHideSubMenu(OnOff: Boolean);
  338.  
  339. This sets whether the sub menus should be dropped before the resulting
  340. event-handler has returned. The default is for the sub menus to remain
  341. visible on the screen (FALSE). If set TRUE then the menus are hidden just
  342. as soon as a selection is made.
  343.  
  344. SetOMDisplayNum(OM : OptionMPtr; Num: Word);
  345.  
  346. This sets the limit on how many menu items to display before an
  347. option menu sprouts a slider bar. If you don't change it then the
  348. menu can be the full size of the screen.
  349.  
  350.  
  351.  
  352.  
  353.  
  354. See the example program 'menudemo.pas' for a comprehensive look at
  355. how a menu system can be set up.
  356.  
  357. ------- END MENUS.TXT
  358.